Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/http-decoupling-transition.md`:
- Around line 93-97: The documentation currently states that
handleChapterAssigned is awaited from chapter-assignments.service.ts at three
call sites, but the actual implementation triggers it fire-and-forget rather
than awaiting it. Update the wording in the "current behavior" section to
accurately reflect that handleChapterAssigned is invoked asynchronously without
awaiting, so the transactional analysis and explanation of why the outbox
pattern is needed remains logically sound and matches the real implementation
behavior.
- Around line 29-39: The fenced code block containing the diagram is missing a
language identifier on the opening fence, which violates markdownlint rule
MD040. Modify the opening fence (the triple backticks before the diagram) to
include a language specifier by adding "text" after the backticks, changing it
from ``` to ```text to satisfy the documentation linting requirements.

In `@src/db/external/ai-schema.ts`:
- Around line 162-164: The patchAiSuggestionJobsSchema is derived from
insertAiSuggestionJobsSchema using partial(), but the insert schema omits
critical fields needed for job state transitions: status, retryCount, and
errorMessage. Define a separate patch schema for patchAiSuggestionJobsSchema
that explicitly includes these fields, allowing patch operations to validate
updates to job lifecycle states. You can achieve this by creating a new schema
definition that combines the necessary fields from the insert schema with the
additional fields required for updates, rather than relying solely on partial()
of the insert schema.
- Around line 109-110: The unique constraint on the ai_suggestion_usage_log
table is incomplete and causes usage data loss when the same user views the same
bible text across multiple project units. Update the unique index definition
named uq_ai_usage_user_text in the ai-schema.ts file to include projectUnitId
alongside userId and bibleTextId. Then locate the corresponding
onConflictDoUpdate target in the ai-suggestions.repository.ts file (around the
insert/conflict handling logic) and update it to also reference projectUnitId in
the conflict resolution criteria to ensure the unique constraint matches
properly.

In `@src/domains/ai-suggestions/ai-suggestions.repository.ts`:
- Around line 180-183: The upsert conflict target in the onConflictDoUpdate call
for the ai_suggestion_usage_log table is incomplete. The target array currently
only includes userId and bibleTextId, but since the table also stores
projectUnitId, you need to add ai_suggestion_usage_log.projectUnitId to the
target array in the onConflictDoUpdate function. This ensures that the upsert
key becomes the composite key of userId, bibleTextId, and projectUnitId, so
separate usage records are preserved for the same user and verse across
different project units instead of overwriting the previous record.

In `@src/domains/ai-suggestions/ai-suggestions.route.ts`:
- Around line 36-54: The responses schema in the route handler is missing a
declaration for the 404 NOT_FOUND response that can be returned by the
requireProjectUnitAccess middleware when a project unit is not found, breaking
the API contract accuracy. Add a [HttpStatusCodes.NOT_FOUND] entry to the
responses object using jsonContent with createMessageObjectSchema and an
appropriate error message describing that the project unit was not found. Apply
this fix to all three routes that use requireProjectUnitAccess as indicated in
the comment.

In `@src/domains/ai-suggestions/ai-suggestions.service.ts`:
- Around line 83-92: The function queueNextVersesForAssignment returns a Result
that indicates success or failure, but the current code ignores this return
value and always returns ok({ queued: true, thresholdMet: true }). Capture the
Result returned by the queueNextVersesForAssignment function call, check if it
represents an error using the Result type's error-checking method, and if so,
propagate that error by returning it instead of the success response. Apply this
fix to all occurrences of this pattern in the file (both at lines 83-92 and at
lines 149-157).

In `@src/domains/chapter-assignments/chapter-assignments.route.ts`:
- Around line 321-339: The responses object for the PATCH ai-status endpoint is
missing a BAD_REQUEST (400) response declaration, which is needed since the
route requires JSON body schema validation. Add a new entry to the responses
object with HttpStatusCodes.BAD_REQUEST as the key, using jsonContent with
createMessageObjectSchema to describe validation failures, following the same
pattern as the other error responses like UNAUTHORIZED and FORBIDDEN. The
description should indicate that the issue is related to invalid request body
formatting.
- Around line 309-313: The requireChapterAssignmentAccess middleware is missing
a case statement to handle CHAPTER_ASSIGNMENT_ACTIONS.TOGGLE_AI in its switch
statement, causing all TOGGLE_AI requests to fail with a 404. Add a new case for
CHAPTER_ASSIGNMENT_ACTIONS.TOGGLE_AI in the switch statement within
requireChapterAssignmentAccess that sets the allowed variable by calling
ChapterAssignmentPolicy.toggleAi with the policyUser and policyAssignment
parameters, then adds a break statement to complete the case.

In `@src/domains/chapter-assignments/chapter-assignments.service.ts`:
- Around line 83-89: The handleChapterAssigned() call is being invoked
synchronously within the transaction scope without checking if AI is enabled for
the assignment, which can cause jobs to be enqueued even if the transaction
rolls back or if the assignment has AI disabled. Refactor this by capturing the
trigger intent (the assignment parameters and AI enabled state) within the
transaction, then defer the actual handleChapterAssigned() call to execute after
successful commit using a post-commit hook or callback. Apply this post-commit
pattern to both occurrences of the handleChapterAssigned() invocation (in the
initial assignment and reassignment paths) and ensure the trigger is only queued
when the assignment's AI state indicates it should be enabled.

---

Outside diff comments:
In
`@src/domains/projects/chapter-assignments/project-chapter-assignments.service.ts`:
- Around line 34-56: Extract the duplicated map logic that transforms the raw
chapter assignment data into the mapped response object into a separate utility
function. This mapper function should accept the raw chapter assignment info
object and return the transformed object with all fields (assignmentId,
projectUnitId, status, bookNameEng, chapterNumber, bibleId, bookId, bookCode,
sourceLangCode, assignedUser, peerChecker, totalVerses, completedVerses,
createdAt, updatedAt, submittedTime, isAiEnabled). Then replace both instances
of the inline map transformation (the one shown in the diff and the identical
one around line 171-195) with calls to this shared mapper function to ensure
consistency across the service and prevent field drift when the response shape
changes.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/ai-suggestions-workflow.md`:
- Around line 26-41: Several fenced blocks in the ai-suggestions-workflow
document are missing language tags, causing markdownlint MD040 warnings. Update
the opening fences for the diagram, pseudocode, system instruction, and endpoint
examples to include an appropriate language specifier such as text, pseudocode,
or http. Focus on the unlabeled fences around the workflow diagrams and the
named sections like Trigger A, Trigger B, pg-boss worker, Step 1–3, system
instruction, GET endpoint, and POST usage endpoint.

In `@src/db/migrations/0012_add_ai_tables.sql`:
- Line 26: The uniqueness key for ai_suggestion_usage_log is missing
projectUnitId, so rows from different project units can collide. Update the
unique index in the migration to scope uniqueness to userId, bibleTextId, and
projectUnitId, and make sure the upsert in ai-suggestions.repository.ts uses the
same three-column conflict target so the inserted projectUnitId always matches
the correct row.

In `@src/db/schema.ts`:
- Around line 533-536: The uniqueness constraint for the AI usage log is too
narrow because `uniqueIndex('uq_ai_usage_user_text')` only covers `userId` and
`bibleTextId`, so it must be expanded to include `projectUnitId` in `schema.ts`.
Update the matching migration so the database constraint matches the schema, and
adjust any upsert conflict target that currently references the old `(userId,
bibleTextId)` key to use the new `projectUnitId`-scoped key. Use the `ai usage`
table definition and any insert/upsert code touching that table to locate the
changes.

In `@src/domains/ai-internal/ai-internal.repository.ts`:
- Around line 172-188: The verse range queries in ai-internal.repository return
arrays without an explicit order, so results from sourceVersesQuery and
targetVersesQuery can come back scrambled. Update both query builders to sort by
verse number in ascending order using an ORDER BY on bible_texts.verseNumber (or
the selected verseNumber field) so multi-verse passages are always returned
deterministically and in sequence.

In `@src/domains/ai-internal/ai-internal.route.ts`:
- Around line 13-26: Update the `/internal/suggestion-context` handler in
`aiInternalService` routing so malformed request JSON from `c.req.json()` is
treated as a client error instead of falling into the generic 500 path. Add
explicit handling in the `server.post` try/catch for JSON parse failures,
alongside the existing `ZodError` branch, and return a 400 with a clear
validation-style message; apply the same fix to `/internal/ai-suggestions` so
both endpoints behave consistently.

In `@src/domains/ai-internal/ai-internal.types.ts`:
- Around line 14-25: The internal suggestion item schema is too strict because
`aiSuggestionItemSchema` requires `modelInfo`, while `upsertAiSuggestions()`
allows it to be missing. Relax `modelInfo` in `aiSuggestionItemSchema` so the
request contract matches the write path, and ensure
`upsertAiSuggestionsRequestSchema` still validates each item through that
updated schema without rejecting valid payloads lacking model metadata.
- Around line 3-10: The validation in suggestionContextRequestSchema is too
strict for canonical book codes, so it rejects valid numbered books handled by
ai-internal.constants. Update the bookCode field in
suggestionContextRequestSchema to accept the canonical 4-character formats used
by codes like 1JN, 2CO, and 1TI, while still supporting the existing valid
codes, and keep the rest of the schema unchanged.

In `@src/domains/ai-suggestions/ai-suggestions.service.ts`:
- Around line 127-129: The enqueue logic in ai-suggestions.service.ts is sending
the full jobs array as one payload, but triggerAiSuggestions expects each queue
item to be a single AiSuggestionTriggerJob object. Update the code around
getQueue() and boss.send(...) so each entry in jobs is enqueued individually,
one send call per job, instead of passing the array wholesale. Keep the payload
shape aligned with what the worker reads from job.data in triggerAiSuggestions.

In `@src/lib/ai-client.ts`:
- Around line 17-24: The AI service request in the fetch call can hang
indefinitely on a half-open connection, blocking the pg-boss worker. Update the
request in the AI client logic to use an AbortController with a bounded timeout,
and ensure the timeout is cleared after the request finishes. Make sure the
timeout is applied around the existing fetch(url, { method: 'POST', headers,
body }) call so failures surface as retryable errors instead of stalling the
handler.

In `@src/workers/ai-trigger.worker.ts`:
- Around line 28-55: The ai-trigger worker currently swallows rejected
triggerAiSuggestions() calls by using Promise.allSettled() and returning error
objects, which lets pg-boss.work() treat failed jobs as successful. Update the
logic in ai-trigger.worker.ts around the jobs.map/Promise.allSettled flow so
rejected jobs are surfaced as actual failures to the worker (or failed
individually) instead of being converted into return values, while keeping the
existing per-job logging in the results loop for the AI trigger job handling.

In `@src/workers/standalone-worker.ts`:
- Around line 68-69: The AI worker is being registered without the shared job
metrics hooks, so its in-flight jobs are not counted during shutdown. Update the
standalone worker registration to pass `metricsHooks` into
`registerAiTriggerWorker`, and update `ai-trigger.worker.ts` so each AI job is
wrapped with the same before/after hooks used by the USFM worker, ensuring
`workerMetrics.activeJobs` and shutdown tracking include both queues.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/ai-suggestions-workflow.md`:
- Around line 176-178: The documentation references the wrong implementation
location for handleChapterAssigned(), which can mislead readers tracing the
workflow. Update the path reference to point to chapter-assignments.service.ts
instead of ai-suggestions.service.ts, using the handleChapterAssigned() symbol
to anchor the corrected location.

In
`@src/domains/projects/chapter-assignments/project-chapter-assignments.service.ts`:
- Around line 236-245: The incremental sync path in buildAssignmentFilter() is
incorrectly returning an empty result when all projectIds are already in
excludeProjectIds, which prevents updated rows from being fetched for the
updatedAfter branch. Keep the already-synced project IDs as the filter input for
repo.getByProjects() when updatedAfter is present, and only use exclusion logic
to decide which project set to query rather than short-circuiting to ok([]).
Locate the fix in buildAssignmentFilter() and preserve the existing
repo.getByProjects() and toMemberChapterAssignmentResponse flow.
- Around line 211-225: The member chapter-assignment response is missing the
isAiEnabled field even though ChapterAssignmentWithProjectId already provides
it, so update toMemberChapterAssignmentResponse to pass that property through.
Also align memberChapterAssignmentResponseSchema in
users-chapter-assignments.types so the response contract includes isAiEnabled
and the mapper/schema stay in sync.

In `@src/env.ts`:
- Around line 47-48: The AI_INBOUND_SERVICE_KEY validation in env.ts is too
permissive because z.string().min(1) allows weak one-character secrets even
though requireServiceAuth uses it as the sole credential. Update the env schema
to enforce a minimum length consistent with the documented 32-character
requirement so invalid values fail fast, and keep the check attached to the
AI_INBOUND_SERVICE_KEY symbol in src/env.ts.

In `@src/workers/ai-trigger.worker.ts`:
- Around line 35-51: The batch in ai-trigger.worker.ts ends too early because
Promise.all() rejects on the first failed job while other triggerAiSuggestions
calls keep running, so onBatchEnd fires before all in-flight work is done.
Update the batching logic in the job-processing path that uses Promise.all and
the logger/metricsHooks callbacks to wait for every job to settle before calling
metricsHooks.onBatchEnd(jobs.length), and preserve per-job success/failure
tracking without aborting the rest of the batch on a single error.

---

Outside diff comments:
In `@src/db/migrations/meta/0012_snapshot.json`:
- Around line 160-179: The snapshot metadata for uq_ai_usage_user_text is stale
and still reflects only user_id and bible_text_id. Update the migration snapshot
JSON so the unique index definition in the snapshot matches schema.ts and
0012_add_ai_features.sql by including project_unit_id in the column list for
uq_ai_usage_user_text. This keeps the Drizzle snapshot in sync with the current
three-column usage-log key and prevents incorrect future diffs.

In `@src/domains/ai-internal/ai-internal.repository.ts`:
- Around line 81-87: The baseWhere filter in aiInternal.repository.ts still
allows whitespace-only translated_verses.content values, which can leak blank
target_text entries into contextVerses. Update the translated_verses.content
condition in the query to match the activation-threshold logic by trimming
content before checking emptiness, and keep the change localized in the
baseWhere construction alongside the existing translated_verses, bible_texts,
and projects predicates.

In `@src/domains/ai-internal/ai-internal.route.ts`:
- Around line 13-28: The handler in ai-internal.route.ts is catching any
SyntaxError from the whole request flow, which can misclassify internal server
errors as invalid JSON. Move the JSON parsing into its own try/catch around
c.req.json() in the /internal/suggestion-context route so only parsing failures
return 400, and let the outer catch in the route continue returning 500 for
other SyntaxError cases. Apply the same scoping fix to the
/internal/ai-suggestions handler as well.

In `@src/domains/ai-suggestions/ai-suggestions.service.ts`:
- Around line 154-167: The initial chapter queueing path in
handleChapterAssigned currently gates only on hasReachedAiActivationThreshold,
so it can enqueue AI jobs even when the chapter toggle is off. Update
handleChapterAssigned to also check isAiEnabled before calling
queueNextVersesForAssignment, using the same AI enablement logic already used by
queueNextVerses so create/reassign flows only enqueue when both conditions are
satisfied.

In `@src/workers/ai-trigger.worker.ts`:
- Around line 24-53: The batch handler in ai-trigger.worker.ts is rethrowing
per-job errors from the Promise.all path, which causes pg-boss to retry the
entire batch and duplicate successful triggerAiSuggestions calls. Update the
QUEUE_NAMES.AI_SUGGESTION_TRIGGER worker to handle failures per job without
rejecting the outer callback, or switch to completing/failing jobs individually
inside the async job processing loop. Keep the existing logger, metricsHooks,
and triggerAiSuggestions flow, but ensure one failed JobPayload does not abort
the whole batch.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/ai-suggestions-workflow.md`:
- Around line 176-178: The documentation references the wrong implementation
location for handleChapterAssigned(), which can mislead readers tracing the
workflow. Update the path reference to point to chapter-assignments.service.ts
instead of ai-suggestions.service.ts, using the handleChapterAssigned() symbol
to anchor the corrected location.

In
`@src/domains/projects/chapter-assignments/project-chapter-assignments.service.ts`:
- Around line 236-245: The incremental sync path in buildAssignmentFilter() is
incorrectly returning an empty result when all projectIds are already in
excludeProjectIds, which prevents updated rows from being fetched for the
updatedAfter branch. Keep the already-synced project IDs as the filter input for
repo.getByProjects() when updatedAfter is present, and only use exclusion logic
to decide which project set to query rather than short-circuiting to ok([]).
Locate the fix in buildAssignmentFilter() and preserve the existing
repo.getByProjects() and toMemberChapterAssignmentResponse flow.
- Around line 211-225: The member chapter-assignment response is missing the
isAiEnabled field even though ChapterAssignmentWithProjectId already provides
it, so update toMemberChapterAssignmentResponse to pass that property through.
Also align memberChapterAssignmentResponseSchema in
users-chapter-assignments.types so the response contract includes isAiEnabled
and the mapper/schema stay in sync.

In `@src/env.ts`:
- Around line 47-48: The AI_INBOUND_SERVICE_KEY validation in env.ts is too
permissive because z.string().min(1) allows weak one-character secrets even
though requireServiceAuth uses it as the sole credential. Update the env schema
to enforce a minimum length consistent with the documented 32-character
requirement so invalid values fail fast, and keep the check attached to the
AI_INBOUND_SERVICE_KEY symbol in src/env.ts.

In `@src/workers/ai-trigger.worker.ts`:
- Around line 35-51: The batch in ai-trigger.worker.ts ends too early because
Promise.all() rejects on the first failed job while other triggerAiSuggestions
calls keep running, so onBatchEnd fires before all in-flight work is done.
Update the batching logic in the job-processing path that uses Promise.all and
the logger/metricsHooks callbacks to wait for every job to settle before calling
metricsHooks.onBatchEnd(jobs.length), and preserve per-job success/failure
tracking without aborting the rest of the batch on a single error.

---

Outside diff comments:
In `@src/db/migrations/meta/0012_snapshot.json`:
- Around line 160-179: The snapshot metadata for uq_ai_usage_user_text is stale
and still reflects only user_id and bible_text_id. Update the migration snapshot
JSON so the unique index definition in the snapshot matches schema.ts and
0012_add_ai_features.sql by including project_unit_id in the column list for
uq_ai_usage_user_text. This keeps the Drizzle snapshot in sync with the current
three-column usage-log key and prevents incorrect future diffs.

In `@src/domains/ai-internal/ai-internal.repository.ts`:
- Around line 81-87: The baseWhere filter in aiInternal.repository.ts still
allows whitespace-only translated_verses.content values, which can leak blank
target_text entries into contextVerses. Update the translated_verses.content
condition in the query to match the activation-threshold logic by trimming
content before checking emptiness, and keep the change localized in the
baseWhere construction alongside the existing translated_verses, bible_texts,
and projects predicates.

In `@src/domains/ai-internal/ai-internal.route.ts`:
- Around line 13-28: The handler in ai-internal.route.ts is catching any
SyntaxError from the whole request flow, which can misclassify internal server
errors as invalid JSON. Move the JSON parsing into its own try/catch around
c.req.json() in the /internal/suggestion-context route so only parsing failures
return 400, and let the outer catch in the route continue returning 500 for
other SyntaxError cases. Apply the same scoping fix to the
/internal/ai-suggestions handler as well.

In `@src/domains/ai-suggestions/ai-suggestions.service.ts`:
- Around line 154-167: The initial chapter queueing path in
handleChapterAssigned currently gates only on hasReachedAiActivationThreshold,
so it can enqueue AI jobs even when the chapter toggle is off. Update
handleChapterAssigned to also check isAiEnabled before calling
queueNextVersesForAssignment, using the same AI enablement logic already used by
queueNextVerses so create/reassign flows only enqueue when both conditions are
satisfied.

In `@src/workers/ai-trigger.worker.ts`:
- Around line 24-53: The batch handler in ai-trigger.worker.ts is rethrowing
per-job errors from the Promise.all path, which causes pg-boss to retry the
entire batch and duplicate successful triggerAiSuggestions calls. Update the
QUEUE_NAMES.AI_SUGGESTION_TRIGGER worker to handle failures per job without
rejecting the outer callback, or switch to completing/failing jobs individually
inside the async job processing loop. Keep the existing logger, metricsHooks,
and triggerAiSuggestions flow, but ensure one failed JobPayload does not abort
the whole batch.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/domains/ai-suggestions/ai-suggestions.repository.test.ts`:
- Around line 6-20: The mock query chain in ai-suggestions.repository.test.ts
leaves mockChain.then with no default resolution, so any await on the chain can
hang if a test forgets to set a per-call implementation. Update the mockChain
setup to give then a safe fallback that resolves or rejects predictably, while
still allowing test-specific overrides, so repository methods using the chain
fail fast instead of timing out.

In `@src/domains/ai-suggestions/ai-suggestions.route.test.ts`:
- Around line 1-146: Add test coverage for POST /ai-suggestions/usage in
ai-suggestions.route.test.ts because trackUsage is mocked but never exercised.
Create a helper similar to postQueueNext to call the usage route, then add cases
that verify auth, permission, and checkProjectUnitAccess behavior plus the user
id guard. Use the existing symbols as anchors: asAuthenticatedUser,
checkProjectUnitAccess, and aiSuggestionsService.trackUsage, and assert a
successful request returns 200 with the expected response shape.

In `@src/middlewares/authenticate.ts`:
- Around line 38-41: The auth bypass in authenticate.ts is too broad because
c.req.path.startsWith('/internal') matches any path sharing that prefix, not
just internal routes. Update the condition in the authenticate middleware to
require a path boundary for the internal prefix, and keep the existing /api/auth
bypass unchanged. Use the authenticate function and its route-check logic as the
place to tighten the matching so only /internal and /internal/... are skipped.

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/domains/ai-suggestions/ai-suggestions.internal.route.ts`:
- Around line 16-31: The internal AI suggestions routes are not guarding
c.req.json(), so malformed or empty JSON can throw before validation and become
a 500. Update both server.post handlers in ai-suggestions.internal.route.ts,
including the /context route and the /results route, to wrap c.req.json() in
try/catch and return a 400 response when parsing fails, then continue with the
existing suggestionContextRequestSchema validation and aiSuggestionsService
calls only after a successful parse.

In `@src/domains/ai-suggestions/ai-suggestions.service.ts`:
- Around line 193-194: Move the hardcoded context cap out of
ai-suggestions.service.ts and into the shared ai-suggestions.constants.ts module
as MAX_CONTEXT_VERSES_TOTAL, then import and use that constant where the current
limit is set in the aiSuggestions service. Remove the inline magic
number/comment pairing so the service references the centralized constant
consistently with the other domain tunables.

In `@src/domains/chapter-assignments/chapter-assignments.service.ts`:
- Around line 207-234: Defer the AI enqueue side effect until after the
assignment transaction is fully committed, because
`chapter-assignments.service.ts` currently calls
`aiSuggestionsService.handleChapterAssigned()` inside `exec`/`db.transaction`
via `result.data.shouldTriggerAi`, which can run before an `externalTx` is
durable. Update the `exec` flow to return the `shouldTriggerAi` signal (and
assignment identifiers) from `result.data.response`, then trigger
`handleChapterAssigned()` only at the outer transaction boundary or in the
caller after commit. Keep the existing `logger.error` handling around
`aiSuggestionsService.handleChapterAssigned`, but move the call so it cannot
fire for a transaction that later rolls back.

In `@src/middlewares/authenticate.ts`:
- Around line 38-41: The auth bypass in authenticate.ts is too broad because
c.req.path.includes('/internal/') will skip session auth for any future route
containing that substring. Update the route check in authenticate() to match the
known internal AI-suggestions prefix explicitly, using a dedicated
prefix/segment test for /ai-suggestions/internal/* instead of a generic
substring, while keeping the /api/auth bypass unchanged.

---

Outside diff comments:
In `@docs/ai-suggestions-internal-consolidation.md`:
- Around line 106-109: The rollout guidance is too vague for the hardcoded
fluent-ai callback URLs, so update the Rollout section to spell out a safe
deploy order or temporary compatibility window. Refer to the fluent-api
route-rename and fluent-ai URL update, and make it explicit which repo should
deploy first, how long both URL shapes must be accepted, and when the old
callback path can be removed.
- Around line 3-6: The document status text is stale and still describes the
consolidated internal-route shape as only “proposed design,” which conflicts
with the branch contents. Update the status wording in this doc so it reflects
the current implemented/merged state and aligns with the rollout guidance; keep
the change localized to the introductory metadata near the audience/status
section, and make sure the terminology matches the surrounding references like
docs/http-decoupling-transition.md and docs/ai-suggestions-workflow.md.

In `@src/domains/chapter-assignments/chapter-assignments.service.ts`:
- Around line 386-411: The comment and transaction usage in chapter assignment
AI toggling are misleading: `handleChapterAssigned` is executed after
`db.transaction(...)` completes, so it is not “inside the transaction,” and the
lone `repo.update` transaction in `chapterAssignmentsService` is unnecessary.
Update or remove the stale comment near the `handleChapterAssigned` call, and
simplify the `db.transaction`/`repo.update` flow so it matches the actual
execution order while keeping the existing error handling in the `isAiEnabled`
branch.